feat: register and audit agent-wallet rules on-chain by MicBun · Pull Request #1388 · trufnetwork/node

MicBun · 2026-06-01T15:11:15Z

resolves: resolves: https://github.com/truflation/website/issues/4035

What

Part 2 of the Modular Agent Addresses (MAA) rule store: the node migration with the rule tables, maa_create, and the
public getters. Stacked on the precompiles PR — this PR's diff is the SQL plus integration tests; the precompiles it
calls live in the base branch.

Depends on (review/merge first):

chore: derive an agent wallet's address from its rules #1387

Changes

Migration 048-maa.sql: maa_rules, maa_allowed_actions, maa_events (append-only audit), maa_create (the
restricted/agent key signs), and 6 public getters. The rule is set once at creation and immutable — committed into
the wallet address via rules_hash. The node computes rules_hash on-chain (never trusts a caller-supplied value), so
the address provably commits to the stored rule.
Integration suite (tests/streams/maa/): asserts on-chain maa_create reproduces the golden-vector address, plus
validation and audit behavior.

Testing

go test -tags kwiltest ./tests/streams/maa/ — pass (~56s)

Notes for reviewers

Rule store only. The execution mechanism (agent acting as the wallet), the theft-prevention gate, and the
withdrawal/fee path are later work, not in this PR.
Two design points are still pending a leadership decision and would need a follow-up if answered against the current
design: (1) whether the funding address and the wallet address are one identity (this PR makes them one); (2) whether
rules stay immutable or become editable (this PR is immutable).

Summary by CodeRabbit

New Features
- Added Modular Agent Address (MAA) system enabling deterministic agent address creation with configurable rules and permissions.
- Support for creating agents with restricted/unrestricted identity pairs and customizable fee configurations.
- Added ability to define and manage allow-listed actions across namespaces.
- Implemented comprehensive audit logging for all agent-related events.

coderabbitai · 2026-06-01T15:11:24Z

Warning

Review limit reached

@MicBun, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 50 minutes and 35 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b796e134-4da7-46f7-b964-6bfa6eb3827c

📥 Commits

Reviewing files that changed from the base of the PR and between 0f26e52 and eb9436e.

📒 Files selected for processing (4)

extensions/tn_utils/maa.go
extensions/tn_utils/maa_test.go
internal/migrations/048-maa.sql
tests/streams/maa/create_test.go

📝 Walkthrough

Walkthrough

This PR adds a complete modular-agent-address (MAA) feature, implementing cryptographic derivation precompiles, SQL persistence layer with validation, and public query API, validated by end-to-end integration tests.

Changes

Modular Agent Address (MAA) Feature

Layer / File(s)	Summary
MAA Precompile Core: Derivation and Rules Hashing `extensions/tn_utils/maa.go`, `extensions/tn_utils/maa_test.go`	Two precompiles implement MAA creation: `derive_maa_address` validates 20-byte restricted/unrestricted and 32-byte rules_hash inputs, builds a canonical preimage, and returns the low 20 bytes of Keccak256. `compute_rules_hash` validates parallel array lengths, fee bounds, bridge type, and body_hash length; normalizes and deduplicates allow-list entries; and encodes a rules preimage including version, fee mode/bps, bridge, and entry count. Comprehensive unit tests verify golden vectors, order-independence, deduplication with "last write wins" semantics, determinism, and rejection of invalid lengths/parameters.
Precompile Method Registration `extensions/tn_utils/precompiles.go`	Both precompile methods are registered into the system precompile bundle.
SQL Schema: MAA Rules, Actions, and Events `internal/migrations/048-maa.sql` (lines 1–107)	Creates `maa_rules` table (immutable rule configuration with fee and custody roles), `maa_allowed_actions` (namespaced action pairs), and `maa_events` (append-only audit log). Adds indexes for address lookups and includes private `maa_record_event` helper to insert audit rows with transaction metadata.
SQL Public Actions: MAA Creation and Validation `internal/migrations/048-maa.sql` (lines 108–218)	`maa_create` treats caller as restricted signer, decodes unrestricted address from hex, validates fee mode/bounds and bridge type, ensures parallel array lengths and no duplicate `(namespace, action)` pairs, invokes precompiles to compute `rules_hash` and derive deterministic `maa_address`, rejects duplicate identities, inserts immutable rule, batch-inserts actions, records `CREATE` audit event, and returns the derived address.
SQL Public Views: MAA Query API `internal/migrations/048-maa.sql` (lines 222–354)	Five read-only views query MAAs: `maa_get_rule` returns rule fields with hex-encoded addresses; `maa_get_allowed_actions` returns sorted action pairs; `maa_list_by_unrestricted` and `maa_list_by_restricted` provide paginated owner-indexed lists; `maa_get_events` returns paginated audit log with tx/block metadata; `maa_is_known` checks MAA existence.
Integration Tests: MAA Creation and Validation `tests/streams/maa/create_test.go`	End-to-end test verifies `maa_create` produces a frozen golden-vector address, `maa_is_known` responds correctly, `maa_get_rule` field mappings (including bridge-to-token derivation and fee settings) and allowed-action ordering are correct, and `maa_get_events` returns a single `CREATE` event with restricted actor role. Additional test confirms rejection of duplicate MAA identity, `restricted == unrestricted`, out-of-range `fee_bps`, duplicate `(namespace, action)` pairs, and unsupported bridge values.

Sequence Diagram

sequenceDiagram
  participant Client
  participant maa_create as maa_create Action
  participant PrecompileDeriv as derive_maa_address
  participant PrecompileRules as compute_rules_hash
  participant maa_rules as maa_rules Table
  participant maa_allowed_actions as maa_allowed_actions Table
  participant maa_events as maa_events Table

  Client->>maa_create: restricted (caller), unrestricted, salt, bridge, fee_mode, fee_bps, fee_flat, namespaces[], actions[], body_hashes[]
  maa_create->>maa_create: validate unrestricted hex decode, fee bounds, bridge, parallel array lengths
  maa_create->>PrecompileRules: fee_mode, fee_bps, fee_flat, bridge, namespaces, actions, body_hashes
  PrecompileRules->>PrecompileRules: deduplicate and sort (namespace, action)
  PrecompileRules->>maa_create: rules_hash (32B)
  maa_create->>PrecompileDeriv: restricted, unrestricted, rules_hash, salt
  PrecompileDeriv->>PrecompileDeriv: build ADDRESS_PREIMAGE, Keccak256
  PrecompileDeriv->>maa_create: maa_address (20B)
  maa_create->>maa_rules: INSERT rule with fee/bridge/token
  maa_create->>maa_allowed_actions: BATCH INSERT allow-listed (namespace, action, body_hash)
  maa_create->>maa_events: INSERT CREATE event with transaction metadata
  maa_create->>Client: return maa_address

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

trufnetwork/node#1387: Directly overlaps with precompile implementations (maa.go, maa_test.go) and precompile wiring in the main PR.
trufnetwork/node#1207: Established the tn_utils precompile framework that this PR extends with new MAA precompile methods.

Suggested labels

type: chore

Poem

🐰 Addresses hashed with care,
Rules and actions sorted fair,
Modular agents in SQL's keep,
Their golden vectors run so deep.
Tests confirm each byte's right place—
A rabbit's blessing on your case!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 53.85% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly summarizes the main objective: implementing on-chain registration and auditing of agent-wallet rules via a new MAA rule store, which is the primary focus across all changed files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/maa-migration

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

holdex · 2026-06-01T15:11:29Z

Time Submission Status

Member	Status	Time	Action	Last Update
MicBun	✅ Submitted	4h	Update time	Jun 2, 2026, 4:58 AM

You can submit time with the command. Example:

@holdex pr submit-time 15m

See available commands to help comply with our Guidelines.

MicBun · 2026-06-01T21:16:48Z

@holdex pr submit-time 4h

…it deletes

# Conflicts: # extensions/tn_utils/maa.go # extensions/tn_utils/maa_test.go

MicBun added 2 commits June 1, 2026 22:08

feat(tn_utils): add maa address derivation precompiles

3f16292

feat(maa): add agent-wallet rule store and audit migration

95a46d0

MicBun self-assigned this Jun 1, 2026

MicBun mentioned this pull request Jun 1, 2026

feat: create and join agent-wallet rules for a fundable address #1386

Merged

MicBun changed the title ~~feat(maa): add agent-wallet rule store and audit migration~~ feat: register and audit agent-wallet rules on-chain Jun 1, 2026

MicBun requested a review from pr-time-tracker June 2, 2026 02:05

Base automatically changed from feat/maa-precompiles to main June 2, 2026 02:05

MicBun added 2 commits June 2, 2026 10:28

maa: derive token from bridge, reject duplicate actions, restrict aud…

389b388

…it deletes

Merge remote-tracking branch 'origin/main' into feat/maa-migration

eb9436e

# Conflicts: # extensions/tn_utils/maa.go # extensions/tn_utils/maa_test.go

MicBun merged commit e44b87c into main Jun 2, 2026
6 of 7 checks passed

MicBun deleted the feat/maa-migration branch June 2, 2026 05:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: register and audit agent-wallet rules on-chain#1388

feat: register and audit agent-wallet rules on-chain#1388
MicBun merged 4 commits into
mainfrom
feat/maa-migration

MicBun commented Jun 1, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 1, 2026 •

edited

Loading

Review limit reached

Walkthrough

Changes

Sequence Diagram

Estimated code review effort

Possibly related PRs

Suggested labels

Poem

❌ Failed checks (1 warning)

Uh oh!

holdex Bot commented Jun 1, 2026 •

edited

Loading

Uh oh!

MicBun commented Jun 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

MicBun commented Jun 1, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Changes

Testing

Notes for reviewers

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

Sequence Diagram

Estimated code review effort

Possibly related PRs

Suggested labels

Poem

❌ Failed checks (1 warning)

Uh oh!

holdex Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Time Submission Status

Uh oh!

MicBun commented Jun 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

MicBun commented Jun 1, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 1, 2026 •

edited

Loading

holdex Bot commented Jun 1, 2026 •

edited

Loading